INPUT

Syntax: INPUT [#chan,] *[ [separator] [prompti$ separator] vari]*
    or: INPUT *[ [#chan,] [separator] [prompti$ separator] vari]*
        (THOR XVI and Minerva v1.97+ only)
Location: QL ROM

This command will read a string of bytes from the specified channel (default #1), which must end in CHR$(10) = <ENTER>. The fetched string is then placed in the specified variable (var), which may be of any type.  Several sets of bytes may be read at the same time by specifying more than one variable, for example by:   

INPUT a$,x,b$

although each set of bytes must again be terminated by CHR$(10). If the channel is write-only (eg. scr), error -15 (bad parameter) will be reported.

If the specified channel is a console channel (con), the cursor will be activated and the user will be able to type in a string of characters at the current text cursor position. The characters typed will appear in the current INK colour on the current STRIP colour, and will also be affected by the settings of CSIZE, UNDER, FLASH and OVER.

If a channel is specified, this must be followed by a comma. It may however also be followed by one or more  separators.  Each separator may be one of the following:

separator       effect
!               If a character other than a space appears
                immediately to the left of the current
                text cursor position, print a space. If
                prompt$ is specified after this, if
                prompt$ is too long to fit on the line
                from the current text cursor position, it
                will be placed at the start of the next
                line. If nothing follows this separator,
                then the text cursor is not moved at the
                end of the command.

,               This forces the text cursor to be placed
                on the next column which is a multiple of
                8.

                Note that anything which appears on screen
                underneath the columns which are stepped
                over will in fact be blanked out in the
                current STRIP colour.

                If the next column which is a multiple of
                8 is at the end of the current line, then
                the comma will move the text cursor to the
                start of the next line, not overwriting
                any text on screen!

\               This forces the text cursor to be placed
                at the start of the next line. If nothing
                follows this separator this has no further
                effect - the text cursor is automatically
                placed at the start of the next line at
                the end of INPUT anyway (see below). This
                has no effect unless nothing follows this
                separator, in which case the text cursor
                is left alone at the end of the command.

TO col          This moves the text cursor to the
                specified column (col). If however, the
                text cursor is already at or beyond the
                specified column, the text cursor
                is moved one space to the right (unless
                you have a THOR XVI - see TO). This
                separator must however be followed by
                yet another separator (normally ; so as
                to avoid confusion).

                If the specified column is further than
                the far right side of the specified
                channel, then TO merely wraps around the
                channel, continuing to count from the
                start of the next line.
  
                Note that any text under the columns which
                are jumped by TO will be blanked out in the
                current STRIP colour.

At the end of the INPUT command, the text cursor is placed at the start of the next print line (unless an end separator of '!',  '\' or ';' is used).

If prompt$ is specified, this will have no effect unless the specified channel (#chan) is a console channel. If this is the case, the specified string is written to the console channel, (as with PRINT), followed by the specified separator. The cursor on the specified channel is then activated at the current print position and input awaited as normal if required.

If you are wondering how to include a variable as part of prompt$, this is achieved by placing the variable in brackets, for example the following will prompt for 3 names to be entered:

100 DIM a$(3,10)
110 FOR i=1 TO 3
120   INPUT 'Enter name number'!(i)!a$(i) TO 40;'-- Thankyou'
130 END FOR i 

Unfortunately, you cannot include the variable which has been entered in that same INPUT statement as a part of prompt$. If you do so, the prompt$ will include the variable at the value it contained at the start of the INPUT statement.

Once the string has been entered, it is assigned to the specified variable and the interpreter then looks at the INPUT command to see if any further prompt$ need to be printed out, or whether any further variables need to be entered; and if so, will repeat the above steps.

NOTE:
If you try to INPUT a string greater than 32766 characters, this may crash the system. It is therefore important that when INPUTting from a file which is longer than 32766 characters, you are certain that it contains a CHR$(10). If not, then use INKEY$.

Pre JS ROMs have a small input buffer, meaning that strings over 128 characters long lead to a 'Buffer Full' (-5) error. You can fix this for QLiberator with a compiler directive.

Minerva Note:
Minerva v1.96+ (as with THOR XVI) will also allow:
 DIM x(4):INPUT x

This will patiently ask you to input the five values of x(0) to x(4).

Minerva v1.96+ (as per THOR XVI) also allows you to insert channel numbers part way through an INPUT statement, although {unlike the THOR XVI implementation}, you still cannot use the variable entered as part of the output.

THOR XVI NOTES:
The THOR XVI (version 6.41) allows you to put channel numbers part way through a statement, for example:  

INPUT 'Your name' ; #0 , name$ \ #1 ; ' is ' ; (name$)

instead of:

PRINT 'Your name ' ; : INPUT #0,name$ : PRINT 'is ';name$

The THOR XVI also allows you to INPUT arrays with one statement. For example:

DIM x(4): INPUT x

will wait around for five values to be entered. No other implementation (other than Minerva v1.96+) currently allows this.

CROSS-REFERENCE:
The text cursor is positioned using commands such as AT and CURSOR.
You may prefer to use EDLINE$ which allows you to provide a default string for alteration, as well as specifying the maximum number of characters that can be typed in.  
PRINT has some similar characteristics. 
HIS_SET allows you to set a history for a console channel.
